home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 10 / AACD 10.iso / AACD / Resources / System / BoingBag1 / Contributions / InstallerNG / GUI-API / README
Text File  |  1999-10-15  |  3KB  |  61 lines
  1. The InstallerNG provides a GUI-API. This API (Aplication Programming
  2. Interface) defines an interface, such that the InstallerNG can have
  3. any GUI. If you want to build a new GUI, you have to write a
  4. shared-library, which has to provide some functions. These functions
  5. may become very complex, because they have to read/write from/to memory,
  6. which is owned by the InstallerNG process. Such memory areas are the
  7. global interpretation environment, which keeps values like the DEFUSER,
  8. LOGFILE, PRETENDMODE etc... Additionally, some functions get a local
  9. environment (like ASKFILE, ASKBOOL, ...), where the parameters, e.g.
  10. the SOURCE, DEST, ad so on for ASKFILE are stored. If you have to access
  11. texts, use the text-array, which comes as an argument for the API function
  12. "igui_InitApp()". Have a look at the example source, which implements a
  13. simple MUI based API.
  14.  
  15. Furthermore, you find some makros and useful tools/functions. See
  16. the "savagelib" drawer for documentation.
  17.  
  18. NOTE: be prepared to add some media related functions to the GUI
  19. (see the #?MEDIA functions of the installer); currently I am not
  20. sure, whether I define them as part of the API or not.....
  21.  
  22. IMPORTANT: if you must allocate memory and cannot free it (see the
  23. igui_AskString function for example) you should use the sav_AllocVec()
  24. function of the savage.lib! this function allocates memory and the
  25. InstallerNG knows about this allocation and frees this memory when
  26. quitting!
  27.  
  28. RULES and HINTS
  29. ===============
  30. - start with a small structure, which describes your private GUI object,
  31.   this could hold window-pointers, gadget pointers etc...
  32.   now you can write the functions igui_InitApp() and igui_FreeApp()
  33.   and, after you have done so, you may start to implement the different
  34.   panels (i.e. write the igui_Ask#?() functions and the other stuff)
  35. - your gui could provide a menu; if so, you have to handle this by your
  36.   own, the InstallerNG itself does not care for that!
  37. - the GUI has to care for locking and unlocking itself; thus, unlock the
  38.   GUI before you have to wait (i.e. before you call igui_QuietWaitApp(),
  39.   which is also called by the InstallerNG itself) and lock the GUI before
  40.   you return from a function, which modified the GUI (like igui_Ask#?()
  41.   or igui_Message() or...)
  42. - have a look at the example source: there you find the documantation for
  43.   every API function and additional example source
  44. - never ever write to the arguments like the environment structures or
  45.   the text array -- they are read only! the only object you are allowed
  46.   to write to is your own custom application structure, which you create
  47.   with igui_InitApp() and which comes as argument for all the functions
  48. - handling GUI errors: if anything goes wrong (e.g. OpenWindow() fails)
  49.   you must set an error code anywhere in your private structure; return
  50.   this error code with igui_Error(), because InstallerNG calls this
  51.   function to check for success of any GUI function and quits, if
  52.   igui_Error() returns a non-zero result
  53. - every function, which modifies the GUI, should leave the GUI empty, i.e.
  54.   with an empty help window (if this is implemented asynchronously, as
  55.   recomented) and an empty panel
  56.  
  57. Have fun,
  58. Jens
  59.  
  60.  
  61.